<html>
<head>
  <title>Table Description</title>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <link rel="stylesheet" type="text/css" href="mystyle.css"/>
  <script type="text/javascript" src="jquery.js"></script>
  <script type="text/javascript" src="menu.js"></script>
  <script type="text/javascript">
    $(document).ready(function() { buildMenus(); });
  </script>
  <script type="text/javascript">var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));</script>
  <script type="text/javascript">try {var pageTracker = _gat._getTracker("UA-7674244-2");pageTracker._trackPageview();} catch(err) {}</script>
</head>
  <body>
    <div id="content">
      <h3>SQL Interface - HOWTO</h3>
      Ok, this isn't the most user-friendly interface.  Other than building lots of pre-defined queries there's not much I can do
      to make it usable for the average person.  But if you've got some programming experience, especially with databases, hopefully
      the information below will help you get the most out of the data.
      <br>
      <br>
      First, take a look at the <a href="images/ERD.png">entity relationship diagram</a> to understand the table structure.  Although most of the data is directly from 
      Kiva, some of it is derived from the data or from external sources.
      <br>
      <br>
      The database uses Oracle 10g.  For a good SQL tutorial check out <a href="http://sqlzoo.net">SQL Zoo</a>, and for a thorough 
      description of the syntax you might want to use the
      <a href="http://download.oracle.com/docs/cd/B19306_01/server.102/b14200/toc.htm">SQL Reference</a>.  The database runs on an 
      old PC, so it may not always be available or very responsive.
      <br>
      <br>
      Most of the data in the tables map directly to data available through the Kiva API.  Many of the fields and terms are explained on <a href="http://build.kiva.org/docs/data">build.kiva.org</a>.  Below are some explainations of the data, as well as areas where my database differs from the Kiva API.  This is not a comprehensive list of the differences, just some information to make the database more useful.<br>
      <ul>
        <li>All dates are in GMT.</li>
        <li>The relationship between Country and Region comes from the Partner API.</li>
        <li>Not every loan has a longitude and latitude at the city level.  Some coordinate are at the country level, and these values are used to populate most of the Country latitude and longitude values.  For countries without this information, I manually chose some coordinates that seemed to be in the center of the country.</li>
        <li>Currency names are from <a href="http://en.wikipedia.org/wiki/ISO_4217">http://en.wikipedia.org/wiki/ISO_4217</a></li>
        <li>loansAvailableWhenPosted was generated from the LOAN data since calculating this data takes many hours.  Each loan is compared with all other loans where the first loans' posted_date falls between the other loans' posted_date and funded_date.  Finding the amount of time to fund a loan is very complicated, and it helps to know what other loans it was competing with.</li>
        <li>MV_Months is a materialized view that is helpful for grouping the data by month or quarter.  It is refreshed everyday, and starts with the earliest data and ends with the current month and quarter.  It is much faster to use these results than to re-query for them when needed.  For some queries it is only useful to look at continuous data, and the column goodDate is used to mark when the data becomes useful for comparison.  Without it many of the charts would look jagged because there are some months without any data.</li>
        <li>Many of the functions need to aggregate strings, which unfortunately is a task that SQL does not handle well.  There are dozens of different approaches to this problem, and my preferred solution is the fastest but also requires some complex features.  For example, this SQL will generate regions and a pipe-separated list of countries in that region:
        <PRE>
        select region, to_string2(cast(collect(name order by name) as varchar2_ntt), '|') countries
        from country
        where region is not null
        group by region</PRE>
        The to_string2 function can be used like any other grouping function.</li>
        <li>The visualizations are created by views.  You can view the code behind the views <a href="code/website views.sql">here</a>.</li>
      </ul>
      </div>
    
    <div id="menu"></div>
  </body>
</html>
